home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / choice.arc / CHOICE.DOC < prev    next >
Text File  |  1987-12-12  |  51KB  |  1,214 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                                        CHOICE
  28.                                      Version 1.1
  29.                           REFERENCE AND INSTALLATION MANUAL
  30.  
  31.  
  32.                                    Copyright  1987
  33.                                    R. S. MacDonald
  34.                                  All rights reserved
  35.  
  36.  
  37.           CHOICE V1.1              COPYRIGHT 1987            R. S. MacDonald
  38.  
  39.                                       CONTENTS
  40.  
  41.  
  42.           INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . .   1
  43.                CONFIGURATION MODE  . . . . . . . . . . . . . . . . . . .   1
  44.                MENU MODE . . . . . . . . . . . . . . . . . . . . . . . .   1
  45.  
  46.           SYSTEM REQUIREMENTS  . . . . . . . . . . . . . . . . . . . . .   2
  47.  
  48.           INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . .   2
  49.                INSTALLC.BAT  . . . . . . . . . . . . . . . . . . . . . .   2
  50.                INSTALLING FOR MENU USE . . . . . . . . . . . . . . . . .   2
  51.                INSTALLING FOR CONFIGURATION USE  . . . . . . . . . . . .   3
  52.                     INSTALLING WITH INSTALLC.BAT . . . . . . . . . . . .   3
  53.                     AUTOEXEC.BAT . . . . . . . . . . . . . . . . . . . .   4
  54.  
  55.           FILE FORMATS . . . . . . . . . . . . . . . . . . . . . . . . .   5
  56.                PROFILE FILES . . . . . . . . . . . . . . . . . . . . . .   5
  57.                MENU FILES  . . . . . . . . . . . . . . . . . . . . . . .   6
  58.  
  59.           PARAMETERS AND OPTIONS . . . . . . . . . . . . . . . . . . . .   7
  60.                EXAMPLES  . . . . . . . . . . . . . . . . . . . . . . . .   8
  61.  
  62.           SCENARIOS  . . . . . . . . . . . . . . . . . . . . . . . . . .   8
  63.                CONFIGURATION MODE  . . . . . . . . . . . . . . . . . . .   8
  64.                     SECURITY OPTION  . . . . . . . . . . . . . . . . . .   8
  65.                     EXAMPLES . . . . . . . . . . . . . . . . . . . . . .   9
  66.                          EXAMPLE 1 . . . . . . . . . . . . . . . . . . .   9
  67.                          EXAMPLE 2:  . . . . . . . . . . . . . . . . . .  10
  68.                     PRECAUTIONS  . . . . . . . . . . . . . . . . . . . .  10
  69.                MENU MODE . . . . . . . . . . . . . . . . . . . . . . . .  11
  70.                     EXAMPLE  . . . . . . . . . . . . . . . . . . . . . .  11
  71.                          EXAMPLE 1 . . . . . . . . . . . . . . . . . . .  11
  72.                          EXAMPLE 2 . . . . . . . . . . . . . . . . . . .  12
  73.                          EXAMPLE 3 . . . . . . . . . . . . . . . . . . .  12
  74.  
  75.           ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . . . .  13
  76.  
  77.           MISCELLANEOUS  . . . . . . . . . . . . . . . . . . . . . . . .  16
  78.  
  79.           WARRANTY . . . . . . . . . . . . . . . . . . . . . . . . . . .  16
  80.  
  81.           LICENSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .  16
  82.  
  83.           CHOICE PLUS  . . . . . . . . . . . . . . . . . . . . . . . . .  17
  84.                OBTAINING CHOICE+ . . . . . . . . . . . . . . . . . . . .  17
  85.  
  86.           CHOICE+ ORDER FORM . . . . . . . . . . . . . . . . . . . . . .  18
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.           CHOICE                                                      Page i
  97.  
  98.  
  99.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  100.  
  101.  
  102.                                     INTRODUCTION
  103.  
  104.           CHOICE is a simple, multi-purpose menu program.  It can be used to
  105.           choose between several applications using only the cursor movement
  106.           and enter keys.  It can also be called from your AUTOEXEC.BAT file
  107.           where it allows you to choose between different configurations.
  108.           After you choose a configuration, CHOICE will replace your
  109.           CONFIG.SYS with the one you chose, create an AUTO1.BAT file, and
  110.           re-boot the system.  CHOICE is distributed as a public domain
  111.           program for personal use only.  Please contact the author if you
  112.           want to use CHOICE for commercial purposes.  Donations for using
  113.           CHOICE are not required, but will not be refused.
  114.  
  115.           An enhanced version of CHOICE, CHOICE+ is also available for a
  116.           small license fee.  It includes the ability to substitute variable
  117.           parameters when calling programs or batch files from menus, an
  118.           editor for building menus and profiles, and several other added
  119.           features.  In this document, those functions included only in
  120.           CHOICE+ are indicated for information purposes.  The actual
  121.           implementation in CHOICE+ may differ slightly from the descrip-
  122.           tions here.
  123.  
  124.           Version 1.1 of CHOICE fixes a problem with an error message if the
  125.           /B option is specified, makes CHOICE ignore menu file records that
  126.           are defined only for CHOICE+ files, and enhances this document
  127.           slightly.
  128.  
  129.  
  130.           CONFIGURATION MODE
  131.  
  132.           When CHOICE is executed by your AUTOEXEC.BAT file in configuration
  133.           mode it will display a menu of choices.  You select one by moving
  134.           the cursor to the desired item and pressing enter.
  135.  
  136.           After that, CHOICE copies the files associated with that menu item
  137.           to files named AUTO1.BAT and CONFIG.SYS.  It then re-boots the
  138.           machine so that the chosen CONFIG.SYS will be used.
  139.  
  140.           When CHOICE is called on the second boot it knows that it caused
  141.           the boot and returns immediately to the AUTOEXEC.BAT that called
  142.           it.  The last statement in AUTOEXEC.BAT should call AUTO1.BAT
  143.           which continues the setup for the configuration that you chose.
  144.  
  145.  
  146.           MENU MODE
  147.  
  148.           When CHOICE is run as a menu program, it displays a menu with up
  149.           to 32 choices.  You can select one with the cursor keys.  When the
  150.           cursor is on your choice, you press enter and choice will run that
  151.           selection.  CHOICE will execute that program or batch file as a
  152.           sub-program to CHOICE.  When the sub-program completes, CHOICE
  153.           will re-display the menu.  The escape key can be used to exit the
  154.           menu.
  155.  
  156.  
  157.  
  158.           CHOICE                                                      Page 1
  159.  
  160.  
  161.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  162.  
  163.  
  164.                                  SYSTEM REQUIREMENTS
  165.  
  166.           The CHOICE.EXE file is about 30K bytes long and requires about 96K
  167.           with DOS 3.2 (plus the size of any programs executed in menu mode)
  168.           to operate.  You must have DOS 2.0 or later (tested on 2.1 and
  169.           3.2).  At least 256K of RAM is recommended for menu use.
  170.  
  171.                                     INSTALLATION
  172.  
  173.           The following files are included in CHOICE11.ARC:
  174.  
  175.                      1. README.1ST       2. CHOICE.DOC
  176.                      3. INSTALLC.BAT     4. CHOICE.EXE
  177.                      5. CHOICEDOC.MNU    6. CHOICE.PRO
  178.                      7. $CONFIG.XXX      8. $CONFIG.YYY
  179.                      9. VANILLA.AUT     10. AUTOCHC1.BAT
  180.                     11. AUTOCHC2.BAT    12. CHOICMNU.BAT
  181.  
  182.  
  183.           The easiest way to install CHOICE is to extract INSTALLC.BAT
  184.           first:
  185.  
  186.                ARC x CHOICE installc.bat
  187.                ARCE CHOICE installc.bat
  188.                PKXARC -X CHOICE installc.bat
  189.  
  190.           Then execute INSTALLC.  For speed, you can move CHOICE11.ARC to a
  191.           RAM disk before extracting files.
  192.  
  193.  
  194.           INSTALLC.BAT
  195.  
  196.           Just enter INSTALLC and CHOICE will give you a menu.  The menu
  197.           items allow you to:
  198.  
  199.                1. Extract the files from CHOICE11.ARC
  200.                2. Display the README.1ST file.
  201.                3. Display, print, or type the documentation file.
  202.                4. Install CHOICE.EXE on disk A, B, C, or D.
  203.                5. Install the examples on any of the above disks.
  204.  
  205.  
  206.           INSTALLING FOR MENU USE
  207.  
  208.           If you are planning to use CHOICE only to provide the menu
  209.           function, you need only to copy CHOICE.EXE to the diskette(s) on
  210.           which you will use it or to a convenient directory on your hard
  211.           disk.  The INSTALLC Install Choice item will put CHOICE.EXE in the
  212.           root directory.  To use CHOICE you will have to build one or more
  213.           menu files.  Menu Files are described in a separate section below.
  214.           See also the examples section for ways to run it.  Sample menu
  215.           files are included in the ARC file.
  216.  
  217.  
  218.  
  219.  
  220.           CHOICE                                                      Page 2
  221.  
  222.  
  223.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  224.  
  225.  
  226.           INSTALLING FOR CONFIGURATION USE
  227.  
  228.           This process is not terribly difficult but requires more than
  229.           merely copying files.  You must build a CHOICE.PRO file (you can
  230.           use the supplied example as a starter), build one or more
  231.           CONFIG.SYS files (naming them something else), then modify
  232.           AUTOEXEC.BAT to call CHOICE and to call AUTO1.BAT as its last
  233.           step.
  234.  
  235.  
  236.           INSTALLING WITH INSTALLC.BAT
  237.  
  238.           INSTALLC will, when you select the proper items, copy CHOICE.EXE
  239.           to the root directory of your boot disk and install the configura-
  240.           tion mode sample files in the root directory of a disk.  The
  241.           procedure that it uses to install the sample files is:
  242.  
  243.                a. If the file SAVECFG.SYS does not exist, rename CONFIG.SYS
  244.                   to that name.  Otherwise, display an error message and
  245.                   skip this step.
  246.                b. If the file SAVEAUTO.BAT does not exist, rename
  247.                   AUTOEXEC.BAT to that name and copy AUTOCHC1.BAT to that
  248.                   name.  Otherwise display an error message and skip this
  249.                   step.
  250.                c. Copy the files CHOICE.PRO, $CONFIG.XXX, $CONFIG.YYY and
  251.                   AUTOCHC2.BAT to the boot disk root directory.
  252.  
  253.           If you do not use INSTALLC, you should do the same things but you
  254.           can use different names for the saved copies of CONFIG.SYS and
  255.           AUTOEXEC.BAT.  Do not skip that step or you may not be able to
  256.           restore your original setup.
  257.  
  258.           After the sample files are installed, you may need to do a few
  259.           more things to make the examples work or to define configurations
  260.           for your daily use.  These are:
  261.  
  262.                a. Edit the CHOICE.PRO file with your favorite editor and
  263.                   modify it according to the directions in the "PROFILE"
  264.                   section below.  This is not required just to use the
  265.                   examples.
  266.                b. Use your editor to modify the first statement in the
  267.                   sample AUTOEXEC.BAT file with valid path names for your
  268.                   disk setup or modify your original AUTOEXEC.BAT file to
  269.                   call CHOICE.  See the example in the AUTOEXEC section
  270.                   below.
  271.                c. Again with your favorite editor, build batch files that
  272.                   can be used as extensions to your AUTOEXEC.BAT file for
  273.                   each of your configurations.  This is not required just to
  274.                   use the examples.
  275.  
  276.           Once you have done the above, you are ready to use CHOICE.  You
  277.           will probably want to define additional configurations.  You can
  278.           do that at any time.  Just use your editor to build the required
  279.           configuration and autoexec extension files and modify the profile
  280.           so that they will be used.
  281.  
  282.           CHOICE                                                      Page 3
  283.  
  284.  
  285.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  286.  
  287.  
  288.           AUTOEXEC.BAT
  289.  
  290.           Your new AUTOEXEC.BAT file will probably be shorter than the one
  291.           you are using now.  You should keep in it only those things that
  292.           you want to do for ALL configurations.  The things that differ
  293.           between configurations will be in your extension batch files.  In
  294.           the description below, refer to the files AUTOCHC1.BAT and
  295.           AUTOCHC2.BAT supplied in the package.  They are sample
  296.           AUTOEXEC.BAT files.
  297.  
  298.           CHOICE.EXE should be called either by the first statement of your
  299.           AUTOEXEC.BAT or right after a PATH statement that allows DOS to
  300.           find it.  In the example below, CHOICE.EXE is assumed to be in one
  301.           of the sub-directories referenced by the PATH statement.  Note
  302.           that the numbers to the left of the statements are not actually in
  303.           the .BAT file but are referenced in the description that follows.
  304.  
  305.           1    PATH c:\;c:\util;c:\dos
  306.           2    CHOICE /P /B
  307.           3    auto1
  308.  
  309.           Statement 1 defines a path that can be used to find the programs
  310.           called by both AUTOEXEC.BAT and AUTO1.BAT.  In statement 2, CHOICE
  311.           is executed with the /B option, which tells it to re-boot the
  312.           system after it gets the configuration name from you.  On the next
  313.           pass, after the re-boot, CHOICE will detect that the system has
  314.           been re-booted and will not do so again.  In that case, the
  315.           AUTO1.BAT file will be executed.  For further examples, see the
  316.           examples in the SCENARIOS section.
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.           CHOICE                                                      Page 4
  345.  
  346.  
  347.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  348.  
  349.  
  350.                                     FILE FORMATS
  351.  
  352.           PROFILE FILES
  353.  
  354.           The CHOICE.PRO, the configuration files and batch files must all
  355.           be in your default directory at the time that CHOICE is executed
  356.           (sorry about that).  CHOICE.EXE can be in another directory if a
  357.           proper path has been defined.
  358.  
  359.           The file CHOICE.PRO describes the configurations that you wish to
  360.           be able to select at boot time.  Each record in the file contains
  361.           an application name (up to 8 characters), the name of the autoexec
  362.           extension batch file (which can include a path but is limited to a
  363.           total of 64 characters), and the name of the configuration file
  364.           (up to 16 characters) that will be copied into a temporary
  365.           CONFIG.SYS file.  Following those fields, you may add a help text
  366.           field if you wish.  The help text will be displayed by CHOICE if
  367.           the cursor is positioned to an application name and F1 is pressed.
  368.           Each of these fields is separated from the next by an exclamation
  369.           mark and one or more blanks.  The following is a sample profile:
  370.  
  371.                chocolat! auto1.cho! config.yum! Basic DOS with 320K VDISK!
  372.                accounts! auto1.bus! config.foo! Direct to Accounting!
  373.                vanilla! auto1.van! config.yum! Basic DOS - No VDISK!
  374.                progdev! AUTO1.BZZ! cfg.pgd! Program Development!
  375.  
  376.           While a profile file is required to run CHOICE, it only needs to
  377.           contain one record.  Of course if it has only one record, then you
  378.           don't need CHOICE.  The format of a profile record is:
  379.  
  380.                Appplication Name: This is displayed to the user in the menu.
  381.                   It has a maximum length of 8 characters.
  382.                Batch Name: the path and name of a batch file that will be
  383.                   invoked after the autoexec.bat as AUTO1.BAT.  It has a
  384.                   maximum length of 64 characters.
  385.                Config Name: the name of a configuration file that will
  386.                   become config.sys for the re-boot.  It has a maximum
  387.                   length of 16 characters.
  388.                Help Text: a description of the application that will be
  389.                   displayed if the user presses F1 when the application name
  390.                   is highlighted in the menu.  It has a maximum length of 64
  391.                   characters.
  392.  
  393.           Notes:
  394.                1. Each field is terminated with an exclamation point. At
  395.                   least one blank must appear before the next field.  The
  396.                   maximum field lengths do not include the exclamation marks
  397.                   or any leading blanks.
  398.                2. The maximum record length is 255 bytes including any extra
  399.                   blanks between fields.
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.           CHOICE                                                      Page 5
  407.  
  408.  
  409.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  410.  
  411.  
  412.           MENU FILES
  413.  
  414.           Menu files are similar to profile files in concept but have a
  415.           slightly different form.  A menu can contain up to 32 menu records
  416.           (no more than 28 are recommended).  Each record has three fields:
  417.  
  418.                Application Name: This field, up to 32 characters long, is
  419.                   displayed on the menu.  It starts in column 1 (or 2 if the
  420.                   menu is within a .BAT file) and ends with an exclamalation
  421.                   point.
  422.  
  423.                Command: A batch or executable file name and any necessary
  424.                   parameters and options with a maximum length of 64
  425.                   characters.  CHOICE will directly execute the command.
  426.                   This field must also be ended with an exclamation point.
  427.  
  428.                Help text: A description of the application up to 64 charac-
  429.                   ters long.  This is used to provide a help display if the
  430.                   user presses F1 when the menu item is highlighted.  It may
  431.                   also be terminated by an exclamation point.
  432.  
  433.           Fields are separated by an exclamation blank and one or more
  434.           blanks.  The maximum record length is 255 bytes.
  435.  
  436.           RESTRICTIONS:
  437.  
  438.           CHOICE will ignore the following records defined for special
  439.           purposes by CHOICE+.  Note that case is ignored in all of these.
  440.  
  441.                - a SET record that assigns values to variables that may be
  442.                   either constant values or descriptions used to ask the
  443.                   user for input.  A set record starts with the word 'SET'
  444.                   which is a reserved word as the first word in the applica-
  445.                   tion name field (:set in batch files).
  446.                - a COMMENT record for documentation only.  It starts with an
  447.                   asterisk (*). An asterisk is not allowed as the first
  448.                   character of the application name field.
  449.                - a MENU LABEL record that allows multiple menus in one file.
  450.                   This record starts with a $ in column 1 (or 2 if batch
  451.                   file).  A dollar sign is also not allowed in the first
  452.                   column of the application name field (:$ in a batch file).
  453.                - an END record to indicate the end of a menu.  It has the
  454.                   form $END (:$END in a batch file).
  455.  
  456.           The menu file can be contained in a batch file (including the one
  457.           that calls CHOICE).  When a menu file extension is .BAT, CHOICE
  458.           scans for the first label record in the file (a record starting
  459.           with a colon) and uses all label records from that point to the
  460.           first non-label record as menu records.  It saves considerable
  461.           disk space on a hard disk to include the menu in the batch file
  462.           that calls CHOICE.
  463.  
  464.  
  465.  
  466.  
  467.  
  468.           CHOICE                                                      Page 6
  469.  
  470.  
  471.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  472.  
  473.  
  474.                                PARAMETERS AND OPTIONS
  475.  
  476.           CHOICE can be invoked with parameters to provide a file name for
  477.           the profile or the menu file.  The command line can also contain
  478.           some option fields that make it work different ways.  The first
  479.           character of an option may be either a slash (/) or a dash (-).
  480.           They are shown with a slash in this documentation.  Options can
  481.           appear anywhere in the command line.
  482.  
  483.           The command syntax is:
  484.  
  485.                CHOICE /M filename [/W]
  486.  
  487.                                          or
  488.  
  489.                CHOICE /P [profile] [/B[1]] [/S] [/T[n]] [/W]
  490.  
  491.           In the above syntax diagram the symbols '['  and ']' mean that
  492.           whatever inside them is optional.  The symbols '<' and '>' mean
  493.           that you can choose between the item groups (separated by a
  494.           vertical bar '|') included within them but ONE must be included.
  495.  
  496.                /M selects the menu mode.  It causes CHOICE to use a menu
  497.                   file rather than a profile file (they are basically
  498.                   similar) and suppresses the boot, secure, and timing
  499.                   options.
  500.                filename is the path, filename, and extension of a menu
  501.                   definition file.
  502.  
  503.                /P selects the profile mode.  It causes choice to use a
  504.                   profile file and allows the boot secure and timing options
  505.                   to be used.
  506.                profile is the path, file name, and extension of either a
  507.                   profile file.  Although it is always referred to in this
  508.                   document as CHOICE.PRO, that name is not required.
  509.                /B tells CHOICE that it should re-boot the machine when it
  510.                   finishes rather than returning to the autoexec.bat file.
  511.                   It will work on a normal IBM PC and on some clones.
  512.                /B1 causes CHOICE to do a forced boot of the system.  It is
  513.                   not used for normal operations.  It will ALWAYS cause a
  514.                   re-boot.
  515.                /S initiates secure mode.  When specified, the user cannot
  516.                   get a list of the profile and cannot use escape to break
  517.                   exit CHOICE.  It offers a minimum amount of security for
  518.                   those who need it.  See the section on security mode for
  519.                   further explanation.
  520.                /T[n] causes CHOICE to start a timeout.  If you do not start
  521.                   to type an application code within n seconds, the applica-
  522.                   tion represented by the first profile record will be
  523.                   selected.  The number of seconds may be any value from 1
  524.                   to 99999.  If the /S option is also present, this option
  525.                   will be ignored.  If the n value is omitted, a default of
  526.                   30 seconds will be used.
  527.  
  528.  
  529.  
  530.           CHOICE                                                      Page 7
  531.  
  532.  
  533.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  534.  
  535.  
  536.                /W causes CHOICE to use the BIOS for video writes instead or
  537.                   writing directly to the screen.  While this is slower, it
  538.                   makes CHOICE a "well-behaved" program as defined by
  539.                   Windows, Topview, and DESQ.  You should use it if you are
  540.                   running under any of the above, although DESQ will allow
  541.                   it to run without the /W option if you tell DESQ that it
  542.                   writes directly to the screen.  /W is the default when a
  543.                   40 column monitor is in use.
  544.  
  545.  
  546.           EXAMPLES
  547.  
  548.           Just to help you see what the command could look like, here are
  549.           two examples that include all possible parameters and options:
  550.  
  551.                CHOICE /M choicdoc.mnu -w
  552.                CHOICE -p choice2.pro -B /W -t30
  553.  
  554.           Note that options and parameters may be in any case and that an
  555.           option can start with either a slash or a dash.
  556.  
  557.  
  558.  
  559.                                       SCENARIOS
  560.  
  561.           CONFIGURATION MODE (/P)
  562.  
  563.           In configuration mode if /S was not specified CHOICE lists the
  564.           application names in a window on the screen along with a prompt to
  565.           select an application code and press enter.  You can move the
  566.           cursor around among the names using the up and down arrow, Home,
  567.           and End keys.  As the cursor is moved around, the selected
  568.           application name will be highlighted.  Once the right name is
  569.           highlighted, pressing Enter will select that configuration.  After
  570.           pressing Enter, CHOICE will  copy the batch and sys files that go
  571.           with that record to AUTO1.BAT and CONFIG.SYS.  If an error occurs
  572.           (such as a non-existing file), an error message will be issued and
  573.           after you press a key, CHOICE will continue as if no error had
  574.           occurred.  Because the error occurred the re-boot will either find
  575.           no CONFIG.SYS or no AUTO1.BAT file.
  576.  
  577.           If you use the /B option, CHOICE will re-boot the system on POR
  578.           and every other time it is called after that (as long as it's flag
  579.           in the DOS user communications area is not changed by another
  580.           program).  If that flag does not exist, it will boot the system
  581.           when it is run.
  582.  
  583.           If you use the /B1 option, CHOICE will re-boot the system every
  584.           time it is run.
  585.  
  586.  
  587.           SECURITY OPTION
  588.  
  589.           The security option offers a minimum amount of security to the
  590.           user of CHOICE in configuration mode.  When the /S option is
  591.  
  592.           CHOICE                                                      Page 8
  593.  
  594.  
  595.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  596.  
  597.  
  598.           included in the command line, CHOICE will not display the choices
  599.           in the configuration menu, nor will the cursor movement or help
  600.           (F1) keys work.  The user must type one of the application names
  601.           in the first field of the profile record (or press Control-Break)
  602.           to exit.  If a non-existent name is typed, CHOICE will display an
  603.           error message in the menu and ask the user to enter an application
  604.           name again.  Since the names are not displayed and the user has no
  605.           easy way to show them while CHOICE is executing, the user will be
  606.           at a loss to determine what to type.  The application name must be
  607.           entered exactly as it appears in the profile including the case.
  608.           CHOICE+ will disable the Control-Break key as well.
  609.  
  610.  
  611.           EXAMPLES
  612.  
  613.           There is a chance of causing problems if the sample files are
  614.           installed and you run CHOICE in configuration mode before getting
  615.           it fully set up.  DO NOT RUN CHOICE IN CONFIGURATION MODE until
  616.           you have saved your CONFIG.SYS and AUTOEXEC.BAT files under other
  617.           names and you are sure that you know what will happen when CHOICE
  618.           is run.  The AUTOEXEC.BAT files are included in the archive file
  619.           under the names AUTOCHC1.BAT and AUTOCHC2.BAT to prevent acciden-
  620.           tal replacement of your current file.
  621.  
  622.  
  623.           EXAMPLE 1:
  624.  
  625.           Assume that the files VANILLA.AUT, $CONFIG.XXX and $CONFIG.YYY
  626.           exist in the root directory and that CHOICE.PRO contains the
  627.           following:
  628.  
  629.           vanilla! vanilla.aut! CONFIG.XXX! Basic Setup.!
  630.           choc! vanilla.aut! config.yyy! Same as vanilla but with VDISK.!
  631.  
  632.           Assume that AUTOEXEC.BAT (from AUTOCHC1.BAT) contains:
  633.  
  634.           echo off
  635.           PATH c:\;c:\bat;c:\util;c:\dos
  636.           CHOICE /P /B /T30
  637.           AUTO1
  638.  
  639.           When CHOICE is executed by AUTOEXEC.BAT and you press enter at
  640.           either of the menu items, it will create (or replace) the file
  641.           AUTO1.BAT by copying VANILLA.AUT, copy either $CONFIG.XXX or
  642.           $CONFIG.YYY to CONFIG.SYS and re-boot the system.  On the boot,
  643.           the new CONFIG.SYS will be used and CHOICE will be executed again.
  644.           It will see that it re-booted the system and exit without display-
  645.           ing a menu.  The last step of AUTOEXEC.BAT will call AUTO1.BAT
  646.           which will do its thing and everything will be cool (we hope).
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.           CHOICE                                                      Page 9
  655.  
  656.  
  657.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  658.  
  659.  
  660.           EXAMPLE 2:
  661.  
  662.           Assume that the files VANILLA.AUT, CONFIG.XXX and CONFIG.YYY exist
  663.           in the root directory and that CHOICE.PRO contains the following:
  664.  
  665.           vanilla! vanilla.aut! CONFIG.XXX! Basic Setup.!
  666.           choc! vanilla.aut! config.yyy! Same as vanilla with VDISK!
  667.  
  668.           Assume that AUTOEXEC.BAT (from AUTOCHC2.BAT) contains:
  669.  
  670.           echo off
  671.           PATH c:\;c:\bat;c:\util;c:\dos
  672.           if exist CONFIG.SYS goto nochc
  673.           CHOICE /P /T30 /B1
  674.           :nochc
  675.           erase config.sys
  676.           AUTO1
  677.  
  678.           When CHOICE is executed by AUTOEXEC.BAT, it will create the file
  679.           AUTO1.BAT by copying VANILLA.AUT, copy either $CONFIG.XXX or
  680.           $CONFIG.YYY to CONFIG.SYS and will re-boot the system because of
  681.           the /B1 option.  On the boot, CONFIG.SYS will be used and CHOICE
  682.           will not be executed again because of the if exist statement.  The
  683.           next line will erase config.sys to prepare for the next boot and
  684.           the last step of AUTOEXEC.BAT will call AUTO1.BAT which will do
  685.           its thing and everything will be cool again.
  686.  
  687.  
  688.           PRECAUTIONS
  689.  
  690.           Be sure to back up your AUTOEXEC.BAT and CONFIG.SYS files before
  691.           you start installation.  If you run this program in configuration
  692.           mode with the sample files installed, THE CONFIG.SYS FILE WILL BE
  693.           REPLACED BY $CONFIG.XXX OR $CONFIG.YYY.  If you have a file called
  694.           AUTO1.BAT you must rename it before attempting an boot with this
  695.           program since it will be replaced by the bat file named in the
  696.           profile.
  697.  
  698.           If you use the /B option you must be sure not to install any
  699.           resident DOS extensions prior to the call to CHOICE.  If you do
  700.           that and one of those extensions has trapped any interrupt vectors
  701.           then the vectors will point to non-existing code points until the
  702.           traps have been set up again.  That could cause things to bomb,
  703.           possibly intermittently.
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.           CHOICE                                                     Page 10
  717.  
  718.  
  719.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  720.  
  721.  
  722.           MENU MODE (/M)
  723.  
  724.           In menu mode, CHOICE is executed with the /M option and one
  725.           parameter: the menu file name.  Any other options are ignored.
  726.           CHOICE will read the menu file records and build a menu of up to
  727.           12 lines on the display screen from the first field of each
  728.           record.  Each line will have either one or two menu options
  729.           depending on the width of your display (if you are running in 40
  730.           column mode, the menu will be 40 columns wide with one column and
  731.           a maximum of 16 choices. Otherwise it will be 80 columns wide with
  732.           two columns and up to 32 choices).
  733.  
  734.           Selection from the menu is done in the same way as in configura-
  735.           tion mode.  You move the cursor to the desired entry with the up,
  736.           down, home, and end keys and press the enter key.  The command in
  737.           the second field of the corresponding menu record will be executed
  738.           as a sub-program of CHOICE.
  739.  
  740.           Just as in configuration mode, a help window will be displayed if
  741.           you press F1.  The third field of the menu file record correspond-
  742.           ing to the cursor position is used for that help information.
  743.  
  744.  
  745.           EXAMPLES
  746.  
  747.           EXAMPLE 1:
  748.  
  749.           You may already have used this example.  It is called by
  750.           INSTALLC.BAT when you ask to see the documentation.  First make
  751.           sure that you are in the directory with all of the files from the
  752.           ARC file,  then print or type the file CHOICDOC.MNU for reference,
  753.           and type:
  754.  
  755.                CHOICE /M choicdoc.mnu
  756.  
  757.           CHOICE will display 3 choices: Display Choice Document, Print
  758.           Choice Document, and Type Choice Document.  If you move the cursor
  759.           to the first choice, the command:
  760.  
  761.                TYPE CHOICE.DOC | MORE
  762.  
  763.           will be executed.  In the second field of the first record,
  764.           CHOICDOC.MNU has that command followed by an exclamation mark to
  765.           end the field.
  766.  
  767.           Moving the cursor to the second choice and pressing enter will
  768.           cause CHOICE.DOC to be copied to the printer.  The third record
  769.           allows you to type the document without using the more filter.
  770.  
  771.           If you have a browse command file available (such as LIST.COM)
  772.           then try modifying the menu file to allow you to use that instead
  773.           of typing the file and using the more filter.  Note that the
  774.           LIST.COM file must be in a directory within your current path
  775.           specification or you must include the path information in the
  776.           second field of the record.
  777.  
  778.           CHOICE                                                     Page 11
  779.  
  780.  
  781.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  782.  
  783.  
  784.           EXAMPLE 2:
  785.  
  786.           In this example, we will run CHOICE in menu mode from a batch
  787.           file.  That allows us to call other batch files from the menu.
  788.           Type CHOICMNU and see what happens.  By examining the batch files
  789.           and the CHOICMNU.BAT file you should be able to tell what will
  790.           happen.  Note that CHOICMNU.BAT uses itself as a menu file.  That
  791.           is possible because CHOICE does two things when its menu file has
  792.           a .BAT extension: it searches for the first label line (starting
  793.           with a colon) and only uses records until it sees a record that is
  794.           not a batch file label.  Thus you can imbed your menu in the batch
  795.           file that uses it by placing the menu records at or near the top
  796.           of the file.  The reason that CHOICE scans for a label record is
  797.           to allow you to have such batch commands as echo off ahead of the
  798.           menu choices.
  799.  
  800.  
  801.           EXAMPLE 3
  802.  
  803.           See the INSTALLC.BAT file for a more complex example of menu use.
  804.           The choices in this menu either call other programs or batch files
  805.           or call INSTALLC again with parameters that cause it to copy
  806.           files, etc.  By displaying this file, you can see how things are
  807.           done.  Note the pause statements that appear after displaying
  808.           error messages or documentation files.  When CHOICE calls a
  809.           program or batch file that types information to the screen, that
  810.           information will disappear when the program or batch file exits.
  811.           It is overlaid by the CHOICE menu and will reappear when you press
  812.           the escape key to exit CHOICE.  If you want to see the messages
  813.           before returning to CHOICE, the function must be run by a batch
  814.           file which has a pause statement in it (unless the program
  815.           displaying the message or data does a keyboard wait before
  816.           exiting).  CHOICE+ has a way around this - a pause option for the
  817.           menu line that causes CHOICE to wait for a keystroke before
  818.           continuing.  CHOICE+ also allows a menu item to specify that it
  819.           should return to DOS after the item is executed instead of
  820.           returning to the menu.
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.           CHOICE                                                     Page 12
  841.  
  842.  
  843.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  844.  
  845.  
  846.                                    ERROR MESSAGES
  847.  
  848.           CHOICE may issue one or more error messages when errors are found
  849.           in the profile or menu or when errors occur while executing an
  850.           application.  When an application is executed, DOS or the
  851.           application can also issue error messages.
  852.  
  853.           CHOICE messages for conditions that are detected while the menu is
  854.           being displayed are shown as a box in reverse video overlaying the
  855.           menu box.  Others, including most issued by applications, are
  856.           typed to the display on the next available line and will remain
  857.           after CHOICE ends.  The following are the messages issued by
  858.           CHOICE:
  859.  
  860.           No profile. Either the name: "filename"
  861.           is spelled wrong or you must build a new one and try again
  862.  
  863.                The profile or menu file that you specified in the command
  864.                line does not exist.  Check that you included the proper path
  865.                information and that you spelled the name correctly, then
  866.                rerun CHOICE.
  867.  
  868.           Error "n" reading in profile or menu "filename"
  869.  
  870.                CHOICE got an error when trying to read the menu or profile
  871.                named in the message.  The file exists, but DOS returned an
  872.                error.  The number "n" is the DOS error number.  CHOICE+ will
  873.                further expand this error message to include a description of
  874.                the error.
  875.  
  876.           Sorry, you must name an application!
  877.  
  878.                This message appears in security mode only.  It is displayed
  879.                when the user types an application name that is not found in
  880.                the profile or if he presses either return or escape.
  881.  
  882.           Error: invalid command segment for entry selected in line "n"
  883.  
  884.                The second field of the menu file is invalid.  The line in
  885.                error (line "n" of the file) is displayed on the next display
  886.                line.  CHOICE terminates on this error.  The most likely
  887.                cause is that the field is too long for CHOICE to handle.
  888.                The command segment must be no longer than 64 characters.
  889.  
  890.  
  891.           Error copying file "filename" to "filename"
  892.  
  893.                This error message appears in a box overlaying the bottom of
  894.                the menu.  A second line from the list that follows is always
  895.                displayed:
  896.  
  897.                   Cannot access output file: "filename"
  898.  
  899.                     DOS has denied access to the file in "filename" - why is
  900.                     unknown.
  901.  
  902.           CHOICE                                                     Page 13
  903.  
  904.  
  905.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  906.  
  907.  
  908.  
  909.                   File already exists: "filename"
  910.  
  911.                     The file named in "filename" already exists and CHOICE
  912.                     cannot overlay it.
  913.  
  914.                   No more file handles for: "filename"
  915.  
  916.                     When choice attempted to open the file named in
  917.                     "filename", DOS said that no more file handles were
  918.                     available.  This message indicated that your config.sys
  919.                     file does not specify enough files.  Locate the FILES=
  920.                     line in your config.sys and increase the number by at
  921.                     least 1 or add the line:
  922.                          FILES=10
  923.                     to your CONFIG.SYS file.
  924.  
  925.                   File or path not found: "filename"
  926.  
  927.                     The file named in "filename" does not exist and was
  928.                     named as an input file in your profile.  Check the
  929.                     spelling and that the correct path is specified.
  930.  
  931.                   Read error on input file "filename"
  932.  
  933.                     DOS got a permanent read error while CHOICE was
  934.                     attempting to copy the file to either config.sys or
  935.                     auto1.bat.  If it happens too often, you probably have a
  936.                     defective disk.  You could try to rename the existing
  937.                     file to another name and build a new file with the
  938.                     original name.  That would make the original file
  939.                     unavailable and probably prevent the error.
  940.  
  941.                   Output file is read only "filename"
  942.  
  943.                     The disk to which you are attempting to copy a file is
  944.                     write-protected or you are trying to reuse the name of a
  945.                     file that is flagged as read-only in the directory.
  946.                     Either remove the protect sticker from the diskette or
  947.                     try a new name.
  948.  
  949.                   Invalid file handle on output "filename"
  950.  
  951.                     This message should never occur.  Contact the author if
  952.                     it does.
  953.  
  954.                   Out of space for output file "filename"
  955.  
  956.                     There is not enough space on the output disk or diskette
  957.                     for the named file.  You must use a different disk or
  958.                     create some space by erasing files.
  959.  
  960.  
  961.  
  962.  
  963.  
  964.           CHOICE                                                     Page 14
  965.  
  966.  
  967.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  968.  
  969.  
  970.                   Unknown error on output "filename"
  971.  
  972.                     This should never occur either.  Please contact the
  973.                     author if you see it.
  974.  
  975.           Invalid record in menu or profile "filename", field "n"
  976.  
  977.                This message is followed, on the next display line, with the
  978.                record found to be invalid.  Check that the fields do not
  979.                exceed the maximum length and that each is terminated by an
  980.                exclamation point and a space (except the last field).
  981.                Correct the error in the menu or profile and rerun CHOICE.
  982.  
  983.           Invalid option: "option"
  984.  
  985.                The option named is invalid.  Check the documentation and try
  986.                again after correcting the error.
  987.  
  988.           Too many parameters supplied. Extra is: "parameter"
  989.  
  990.                CHOICE accepts only one parameter in menu mode or two in
  991.                configuration mode.  Be sure that you have specified the
  992.                correct mode.
  993.  
  994.  
  995.           Error Messages issued only by CHOICE+:
  996.  
  997.           Error "n" processing SET record from "filename"
  998.  
  999.           Invalid variable ID: "varid" - must be %1 to %255
  1000.  
  1001.           Out of memory space for variable "varid"
  1002.  
  1003.           Too many variables.
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.           CHOICE                                                     Page 15
  1027.  
  1028.  
  1029.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  1030.  
  1031.  
  1032.                                     MISCELLANEOUS
  1033.  
  1034.           CHOICE was compiled with the Microsoft C compiler Version 5.0.
  1035.           CHOICE has been tested on an IBM PC* and IBM PC-XT under PC DOS
  1036.           releases 2.1 and 3.2.  It should work on other models of PCs and
  1037.           reasonably close IBM PC compatible machines under any PC DOS (or
  1038.           MS DOS) release from 2.0 up.  DOS releases 1.0 and 1.1 will not
  1039.           work.  If you have any problems, you can contact me via electronic
  1040.           mail to 72617,1456 on Compuserve, to BEL471 on The Source or by
  1041.           regular mail to:
  1042.  
  1043.                     CHOICEWARE
  1044.                     776 14th Street
  1045.                     Boulder, CO  80302
  1046.  
  1047.  
  1048.                                       WARRANTY
  1049.  
  1050.           CHOICE is supplied "as is" without warranty of any kind, either
  1051.           expressed or implied.  We will not be responsible for damages or
  1052.           loss, including special, incidental, or consequential damages,
  1053.           resulting from the use of this program.  We will endeavor to fix
  1054.           problems that prevent this program from working correctly on any
  1055.           IBM PC compatible computer as long as you can describe what is
  1056.           required.  Since this is a public domain program, supported
  1057.           without charge, fixes will be made only by uploading the archive
  1058.           file to either Compuserve and/or The Source or both at my
  1059.           convenience.
  1060.  
  1061.           CHOICE is copyrighted by Richard S. MacDonald in 1987.  All rights
  1062.           reserved.
  1063.  
  1064.                                        LICENSE
  1065.  
  1066.           You are hereby licensed to use CHOICE for personal, non-commercial
  1067.           purposes only (including for non-profit charitable organizations).
  1068.           You may copy the CHOICE11.ARC file and distribute it, without
  1069.           additions, deletions, or changes to others without charge,
  1070.           including uploading the file to one or more non-commercial
  1071.           bulletin board systems.  You may place the CHOICE11.ARC file in
  1072.           computer club libraries and distribute it to members so long as no
  1073.           charge other than a reasonable duplicating cost (no more than $3
  1074.           per disk) is charged.  CHOICE may not be used for commercial
  1075.           purposes without the express written permission of the author or
  1076.           his assignees and payment of such fees as are agreed upon.  Please
  1077.           contact CHOICEWARE for corporate or site licenses.
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.                * IBM, IBM PC, IBM PC-XT, etc. are registered trademarks of
  1086.           International Business Machines Corporation.
  1087.  
  1088.           CHOICE                                                     Page 16
  1089.  
  1090.  
  1091.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  1092.  
  1093.  
  1094.                                      CHOICE PLUS
  1095.  
  1096.           As mentioned on the first page, an enhanced version of CHOICE is
  1097.           available for a license fee.  CHOICE+ adds a number of features
  1098.           that make CHOICE more powerful and easier to use.  In menu mode,
  1099.           CHOICE+ can be told to pause and wait for a key to be pressed
  1100.           after executing a program or batch file.  In many cases this
  1101.           allows a program to be called directly from CHOICE without calling
  1102.           an intermediate batch file and speeds execution, reduces memory
  1103.           overhead and avoids wasting disk space.  CHOICE+ can also be told
  1104.           to exit CHOICE+ after a command is executed instead of returning
  1105.           to the menu.
  1106.  
  1107.           CHOICE+ also offers dynamic substitution of fields in commands
  1108.           called by CHOICE.  Fields in the command field of a menu record
  1109.           may be represented by a variable in the form %n (where n is a
  1110.           number from 0 to 99).  In either case, CHOICE+ searches the
  1111.           variables defined in any SET records found in the menu file.  If
  1112.           the variable is not found CHOICE+ issues an error message and
  1113.           ignores the field.  If it is found, CHOICE+ looks at the value set
  1114.           in the set record.  If the first character of the string to which
  1115.           the variable is set is an asterisk, CHOICE+ will use the assigned
  1116.           value.  If not, CHOICE+ asks the user to supply the value for the
  1117.           variable, displaying the string assigned in the SET statement as a
  1118.           question.  The resulting value is then substituted in the command
  1119.           string when the program is called.
  1120.  
  1121.           To save disk space, CHOICE+ allows more than one menu to be
  1122.           imbedded within a batch or menu file.
  1123.  
  1124.           The CHOICE+ package also includes a menu build program.  It is a
  1125.           simple editor that allows you to enter the fields for each record
  1126.           in a menu file.  It checks for valid field and record lengths and,
  1127.           when you tell it to end, asks for text to be assigned to any
  1128.           variables entered in command fields and builds SET records for
  1129.           them.
  1130.  
  1131.  
  1132.           OBTAINING CHOICE+:
  1133.  
  1134.           CHOICE+ is available from CHOICEWARE for a fee of $25.00 U.S.  The
  1135.           package consists of one disk containing the program, documentation
  1136.           and sample files.  If you prefer printed documentation, include an
  1137.           additional $10.  The documentation will be photo-copied on either
  1138.           5 1/2" by 8 1/2" paper punched to fit a standard PC documentation
  1139.           binder or on 8 1/2" by 11" paper punched to fit a standard 3-hole
  1140.           binder.  For your convenience, and order form is on the last page
  1141.           of this document.  The same form may be used to get on our mailing
  1142.           list for announcements of new programs and updates.
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.           CHOICE                                                     Page 17
  1151.  
  1152.  
  1153.           CHOICE V1.1                Copyright 1987          R. S. MacDonald
  1154.  
  1155.  
  1156.                                    CHOICE+ ORDER FORM
  1157.  
  1158.  
  1159.       TO:  CHOICEWARE
  1160.            776 14th Street
  1161.            Boulder, CO  80302
  1162.  
  1163.  
  1164.       ORDERED BY:                            SHIP TO:
  1165.  
  1166.       Name: ____________________________     Name:_______________________________
  1167.  
  1168.       Company: _________________________     Company:____________________________
  1169.  
  1170.       Street: __________________________     Street: ____________________________
  1171.  
  1172.       City:_____________________________     City:_______________________________
  1173.  
  1174.       State: _____ ZIP: ___________          State: _____ ZIP: ___________
  1175.  
  1176.  
  1177.  
  1178.                PRODUCT                            QUANTITY   PRICE     TOTAL
  1179.  
  1180.       CHOICE+ . . . . . . . . . . . . . . . . . . ________   $25.00   _________
  1181.  
  1182.       CHOICE+ Hard Copy Documentation . . . . . . ________   $10.00   _________
  1183.  
  1184.       RUSH Shipping (Second day air). . . . . . . . . . . .  $10.00   _________
  1185.  
  1186.       TOTAL AMOUNT INCLUDED WITH ORDER. . . . . . . . . . . . . . . .$ ________
  1187.  
  1188.  
  1189.       MEDIA: 5 1/4" DSDD ______  5 1/4" SSDD ______  3 1/2" 720K _____
  1190.  
  1191.       I prefer hard copy documentation in the following format:
  1192.  
  1193.                5 1/2" X 8 1/2"  ____     8 1/2" X 11"     ____
  1194.  
  1195.       I wish to be on your mailing list for new product
  1196.  
  1197.       announcements:        YES _____      NO _____
  1198.  
  1199.       Comments (Please continue on reverse): _____________________________________
  1200.  
  1201.       ____________________________________________________________________________
  1202.  
  1203.       ____________________________________________________________________________
  1204.  
  1205.       ____________________________________________________________________________
  1206.  
  1207.       Thank you for your order.  We appreciate your business.
  1208.  
  1209.  
  1210.  
  1211.  
  1212.           CHOICE                                                     Page 18
  1213.  
  1214.